home *** CD-ROM | disk | FTP | other *** search
/ Gold Medal Software 2 / Gold Medal Software Volume 2 (Gold Medal) (1994).iso / bbsutils / sapphc.arj / ACCOUNT.DOC < prev    next >
Text File  |  1994-01-01  |  14KB  |  311 lines
  1. ╔═════════════════════════════════════════════════════════════════════════════╗
  2. ║ ▒░▒░▒░▒░▒░▒░▒░▒░▒░▒░▒                                 ▒░▒░▒░▒░▒░▒░▒░▒░▒░▒░▒ ║
  3. ║ ░▒░▒░▒░▒░▒░▒░▒░▒░▒░▒░    SAPPHIRE USAGE ACCOUNTING    ░▒░▒░▒░▒░▒░▒░▒░▒░▒░▒░ ║
  4. ║ ▒░▒░▒░▒░▒░▒░▒░▒░▒░▒░▒                                 ▒░▒░▒░▒░▒░▒░▒░▒░▒░▒░▒ ║
  5. ╚═════════════════════════════════════════════════════════════════════════════╝
  6.  
  7.  
  8. ╔═════════════════════════════════════════════════════════════════════════════╗
  9. ║ WARNING:  Sapphire Accounting,  when properly implemented,  is a Zero-Main- ║
  10. ║ tenance feature.  However, if you turn on accounting and do not also set up ║
  11. ║ the event to  export and purge  the information file,  you can fill up your ║
  12. ║ disk.  By default, Sapphire Accounting is turned OFF.                       ║
  13. ╚═════════════════════════════════════════════════════════════════════════════╝
  14.  
  15.  
  16.  
  17. WHAT IS SAPPHIRE ACCOUNTING?
  18. ════════════════════════════
  19.  
  20. Sapphire Accounting enables you to export usage records to another program so
  21. you can bill users for their online time and downloads.
  22.  
  23. If you turn on Sapphire's accounting feature (SYSOP:CONFIG:SECURITY:ACCOUNTING)
  24. each download and user session will generate an accounting record in a text
  25. file named SAPPHIRE.ACC.  You can set up a daily event (using Sapphire's EVENT
  26. command) to extract the accounting data you need, then send the data to
  27. another program for processing.
  28.  
  29.  
  30.  
  31. EXTRACTING THE DATA
  32. ═══════════════════
  33.  
  34. One convenient way to pre-process the data is with Pinnacle Software's
  35. Parse-O-Matic program.  This handy utility extracts and reformats data in a
  36. text file according to rules you specify.  The file ACCOUNT.POM is a
  37. Parse-O-Matic control file created for Sapphire Accounting.  It will read the
  38. accounting file, strip out certain unwanted data, and create a "comma-
  39. delimited" file appropriate for importing into a spreadsheet.
  40.  
  41. To try it out:
  42.  
  43.   1)  Obtain the Parse-O-Matic program (evaluation copy $6 by mail, or free
  44.       from our support BBS at 514-345-8654; registered copy: $25) and install
  45.       it in your Sapphire directory (or preferably, in a utility directory in
  46.       your DOS PATH).
  47.  
  48.   2)  Turn on accounting via SYSOP:CONFIG:SECURITY:ACCOUNTING.
  49.  
  50.   3)  Start up Sapphire.
  51.  
  52.   4)  Log on and off a few times to create some accounting data.
  53.  
  54.   5)  Shut down Sapphire.
  55.  
  56.   6)  Run Parse-O-Matic by entering this command at the DOS prompt:
  57.  
  58.       POM ACCOUNT.POM SAPPHIRE.ACC TEST.TXT
  59.  
  60.       This will process the accounting data file SAPPHIRE.ACC according to the
  61.       rules in the Parse-O-Matic control file ACCOUNT.POM and place the result
  62.       in the file TEST.TXT.
  63.  
  64.   7)  Enter the command SEE TEST.TXT to view the resulting file.  This is a
  65.       comma-delimited file appropriate for importation into another program
  66.       such as a spreadsheet (e.g. Lotus 1-2-3, Excel, Quattro Pro) or database
  67.       (e.g. Paradox, DBase).
  68.  
  69.   8)  If you find that the information in TEST.TXT is not quite right for your
  70.       application (wrong format, missing or unwanted data), you can modify the
  71.       Parse-O-Matic control file (ACCOUNT.POM) using a text editor.  Be sure
  72.       to make a backup copy first.
  73.  
  74.  
  75.  
  76. SETTING UP THE EVENT
  77. ════════════════════
  78.  
  79. Once you have created a Parse-O-Matic control file appropriate to your needs,
  80. you will set up the batch file to be called by the daily event.  The batch
  81. file will look something like the following example (a copy of which is
  82. available in the file ACCOUNT.BAT):
  83.  
  84. BATCH FILE LINE                           EXPLANATION
  85. ────────────────────────────────────────  ─────────────────────────────────────
  86. @ECHO OFF                                 Turn off batch file echo
  87. POM ACCOUNT.POM SAPPHIRE.ACC ACCOUNT.TMP  Run Parse-O-Matic
  88. IF ERRORLEVEL 1 GOTO ERR                  Quit if some kind of data error
  89. REM - - - - - - - - - - - - - - - - - -   Comment line
  90. REM Run import procedure here             Comment line
  91. REM - - - - - - - - - - - - - - - - - -   Comment line
  92. GOTO SAVE                                 Jump ahead to SAVE label
  93. :ERR                                      Batch file label
  94. COPY ACC.ERR+SAPPHIRE.ACC ACC.ERR         Preserve the data
  95. :SAVE                                     Batch file label
  96. IF EXIST SAPPHIRE.AC$ DEL SAPPHIRE.AC$    Delete backup copy of accounting data
  97. RENAME SAPPHIRE.ACC SAPPHIRE.AC$          Make the data file a backup copy
  98.  
  99. The various steps of the event are described in more detail, below.
  100.  
  101.  
  102. THE PARSING PROCEDURE
  103. ─────────────────────
  104.  
  105. The batch file runs Parse-O-Matic (the POM command) to extract data from the
  106. file SAPPHIRE.ACC, according to the rules specified in the Parse-O-Matic
  107. control file ACCOUNT.POM.  The resulting data is placed in the file
  108. ACCOUNT.TMP.
  109.  
  110.  
  111. THE IMPORT PROCEDURE
  112. ────────────────────
  113.  
  114. The import procedure (indicated by comments in the sample batch file) is the
  115. step that actually reads the extracted data (which resides in the file
  116. ACCOUNT.TMP) into your spreadsheet or database.  You will have to write a
  117. spreadsheet or database script or macro to perform the import.  Alternatively,
  118. you can use a DOS keyboard stacker utility (such as "STACKKEY"), or a keyboard
  119. macro processor (such as Superkey or Newkey) to play back the keystrokes
  120. required to perform the import.
  121.  
  122.  
  123. THE ERROR TRAPPING PROCEDURE
  124. ────────────────────────────
  125.  
  126. After Parse-O-Matic is run, the batch file checks the DOS ERRORLEVEL.  In the
  127. unlikely event that it is set to 1 or higher, it means that something went
  128. wrong in the data extraction step, so the batch file jumps to the :ERR label
  129. -- skipping the import procedure.
  130.  
  131. The error handling procedure executes this command:
  132.  
  133.   COPY ACC.ERR+SAPPHIRE.ACC ACC.ERR
  134.  
  135. This command will place the raw accounting data at the end of the file
  136. ACC.ERR.  Thus, even if you don't notice the error for several days, you won't
  137. lose any data -- it will be preserved in the file ACC.ERR.
  138.  
  139.  
  140. AFTER THE EVENT
  141. ───────────────
  142.  
  143. There is no need to add code to the batch file to start up Sapphire.  The
  144. event-processing feature of Sapphire actually runs a copy of the batch file
  145. (rather than the batch file itself) and adds the necessary commands to restart
  146. the BBS.
  147.  
  148. After the batch file is run, the file SAPPHIRE.ACC is gone -- it is renamed to
  149. SAPPHIRE.AC$ by the batch file -- but it will be recreated automatically by
  150. Sapphire.
  151.  
  152.  
  153.  
  154. ACCOUNTING RECORD TYPES
  155. ═══════════════════════
  156.  
  157. Several kinds of records appear in the accounting log:
  158.  
  159.   TYPE  DESCRIPTION
  160.   ────  ──────────────────────
  161.    A    Arrival record
  162.    D    Download record
  163.    S    Session summary record
  164.  
  165. These are described in more detail, below.
  166.  
  167.  
  168.  
  169. THE ARRIVAL RECORD
  170. ══════════════════
  171.  
  172. A "Type A" record contains the letter "A" in column one.  It looks like this:
  173.  
  174. ╔════════╤═════════════════════════════════════════════════════════════════════╗
  175. ║ COLUMN │  ∙∙∙∙■∙∙∙10∙∙∙∙■∙∙∙20∙∙∙∙■∙∙∙30∙∙∙∙■∙∙∙40∙∙∙                        ║
  176. ║        │    ════════════════════ ════════════════════                        ║
  177. ║ DATA   │  S AAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAA                        ║
  178. ║        │    ════════════════════ ════════════════════                        ║
  179. ║        │    REAL NAME            USER NAME                                   ║
  180. ╚════════╧═════════════════════════════════════════════════════════════════════╝
  181.  
  182. The fields are as follows:
  183.  
  184. START   FIELD
  185. COLUMN  LENGTH   DESCRIPTION
  186. ──────  ──────   ───────────
  187.     1      1     The letter "A" -- this identifies a "Type A" record
  188.     3     20     The user's real name (as entered during sign-up)
  189.    24     20     The user's sign-on name (sometimes called "Handle" or "Alias")
  190.  
  191.  
  192.  
  193. THE DOWNLOAD RECORD
  194. ═══════════════════
  195.  
  196. A "Type D" record contains the letter "D" in column one.  It is written to the
  197. accounting file whenever the user successfully completes a download.  It looks
  198. like this:
  199.  
  200. ╔════════╤═════════════════════════════════════════════════════════════════════╗
  201. ║ COLUMN │  ∙∙∙∙■∙∙∙10∙∙∙∙■∙∙∙20∙∙∙∙■∙∙∙30∙                                    ║
  202. ║        │    ════════ ═══ L F P ══════════                                    ║
  203. ║ DATA   │  D AAAAAAAA AAA E A R NNNNNNNNNN                                    ║
  204. ║        │    ════════ ═══ V   O ══════════                                    ║
  205. ║        │    ROOTNAME EXT       FILE SIZE                                     ║
  206. ╚════════╧═════════════════════════════════════════════════════════════════════╝
  207.  
  208. The fields identify a file that was downloaded, as follows:
  209.  
  210. START   FIELD
  211. COLUMN  LENGTH   DESCRIPTION
  212. ──────  ──────   ───────────
  213.     1      1     The letter "D" -- this identifies a "Type D" record
  214.     3      8     Root name of the file (e.g. XYZ.DAT's root is XYZ)
  215.    12      3     Extension of the file (e.g. XYZ.DAT's extension is DAT)
  216.    16      1     Minimum level required to download this file
  217.    18      1     File area in which the file was placed
  218.    20      1     Protocol used to download the file
  219.    22     10     Size of the file in bytes (not kilobytes, as in other records)
  220.  
  221.  
  222.  
  223. THE SESSION SUMMARY RECORD
  224. ══════════════════════════
  225.  
  226. A "Type S" record contains the letter "S" in column one.  Using the default
  227. format, the record looks like this:
  228.           
  229. ╔════════╤═════════════════════════════════════════════════════════════════════╗
  230. ║ COLUMN │  ∙∙∙∙■∙∙∙10∙∙∙∙■∙∙∙20∙∙∙∙■∙∙∙30∙∙∙∙■∙∙∙40∙∙∙∙■∙∙∙50∙∙∙∙■∙∙∙60∙∙∙∙■  ║
  231. ║        │    ════════════════════ ════════════════════ L ═════ ══════════     ║
  232. ║ DATA   │  S AAAAAAAAAAAAAAAAAAAA AAAAAAAAAAAAAAAAAAAA E NNNNN DDDDD MMMM     ║
  233. ║        │    ════════════════════ ════════════════════ V ═════ ══════════     ║
  234. ║        │    REAL NAME            USER NAME              CALLS LAST CALL      ║
  235. ╟────────┼─────────────────────────────────────────────────────────────────────╢
  236. ║ COLUMN │  ∙∙∙70∙∙∙∙■∙∙∙80∙∙∙∙■∙∙∙90∙∙∙∙■∙∙100∙∙∙∙■∙∙110∙∙∙∙■∙∙120∙∙∙∙■∙∙130  ║
  237. ║        │  ══════════════════════════════   ══════════════════════════════    ║
  238. ║ DATA   │  YY/MM/DD HH:MM:SS DDDDD MMMM W   YY/MM/DD HH:MM:SS DDDDD MMMM W    ║
  239. ║        │  ══════════════════════════════   ══════════════════════════════    ║
  240. ║        │  START OF CALL                    END OF CALL                       ║
  241. ╟────────┼─────────────────────────────────────────────────────────────────────╢
  242. ║ COLUMN │  ∙∙∙∙■∙∙140∙∙∙∙■∙∙150∙∙∙∙■∙∙160∙∙∙∙■∙∙170∙∙∙∙■∙∙180∙∙∙∙■∙∙190∙∙∙∙■  ║
  243. ║        │  ═════ ═════ ═════════ ═════════   ═════ ═════ ═════════ ═════════  ║
  244. ║ DATA   │  NNNNN NNNNN NNNNNNNNN NNNNNNNNN   NNNNN NNNNN NNNNNNNNN NNNNNNNNN  ║
  245. ║        │  ═════ ═════ ═════════ ═════════   ═════ ═════ ═════════ ═════════  ║
  246. ║        │  SESSN TOTAL SESSION   TOTAL       SESSN TOTAL SESSION   TOTAL      ║
  247. ║        │  DNLDS DNLDS DOWNLOADK DOWNLOADK   UPLDS UPLDS UPLOADK   UPLOADK    ║
  248. ╟────────┼─────────────────────────────────────────────────────────────────────╢
  249. ║ COLUMN │  ∙∙200∙∙∙∙■∙∙210∙∙∙∙■∙∙220∙∙∙∙■∙∙230                                ║
  250. ║        │       ═════ ═════   ════════════════    ┌────────────────────────┐  ║
  251. ║ DATA   │       NNNNN NNNNN   ****************    │    Blank spaces are    │  ║
  252. ║        │       ═════ ═════   ════════════════    │ reserved for expansion │  ║
  253. ║        │       SESSN TOTAL   READ FLAGS          └────────────────────────┘  ║
  254. ║        │       POSTS POSTS                                                   ║
  255. ╚════════╧═════════════════════════════════════════════════════════════════════╝
  256.  
  257. Using the default format, the fields are as follows:
  258.  
  259. START   FIELD
  260. COLUMN  LENGTH   DESCRIPTION
  261. ──────  ──────   ───────────
  262.     1      1     The letter "S" -- this identifies a "Type S" record
  263.     3     20     The user's real name (as entered during sign-up)
  264.    24     20     The user's sign-on name (sometimes called "Handle" or "Alias")
  265.    45      1     User level (0 to 8)
  266.    47      5     Total number of visits by this user (*)
  267.    53      5     Day # of previous call from this user
  268.    59      4     Minute-of-day of previous call from this user
  269.    66      8     Start of call date (Year/Month/Date format)
  270.    75      8     Start of call time (Hour:Minute:Second format)
  271.    84      5     Start of call day #        
  272.    90      4     Start of call minute-of-day
  273.    95      1     Start of call day-of-week (0=Sunday, 1=Monday ... 6=Saturday)
  274.    99      8     End of call date (Year/Month/Date format)
  275.   108      8     End of call time (Hour:Minute:Second format)
  276.   117      5     End of call day #
  277.   123      4     End of call minute-of-day
  278.   128      1     End of call day-of-week (0=Sunday, 1=Monday ... 6=Saturday)
  279.   131      5     Number of downloads  (this call)
  280.   139      5     Number of downloads  (all calls)
  281.   143      9     Kilobytes downloaded (this call)
  282.   153      9     Kilobytes downloaded (all calls)
  283.   165      5     Number of uploads    (this call)
  284.   171      5     Number of uploads    (all calls)
  285.   177      9     Kilobytes uploaded   (this call)
  286.   187      9     Kilobytes uploaded   (all calls)
  287.   201      5     Number of SENDs      (this call)
  288.   207      5     Number of SENDs      (all calls)
  289.   215      1     Read flag:   Checked OBSERVE  ("*" for Yes, "-" for No)
  290.   216     15     Read flags:  15 message bases ("*" if read, "-" if not)
  291.  
  292. (*) For reasons relating to its internal data format, Sapphire stops 
  293.     incrementing this value when it reaches 65000 visits.
  294.  
  295. The read flags for message bases are set (i.e. show "*") only if the user
  296. actually saw some new messages.  The "*" will not be set if he entered a READ 
  297. command for a particular base and saw nothing there, or if he used SET to 
  298. back up to earlier messages.
  299.  
  300. Except for "Start of Call" data, all data is obtained at the END of the call.
  301. So if you alter a user's level during the call (via function key), the
  302. modified level will be recorded.
  303.  
  304. The record format shown above will change if you set a different date format.
  305. The default date format is YY/MM/DD (Year, Month, Day).  However, you can set
  306. a different date format if you wish, using the CONFIG program:
  307.  
  308.   - Select SYSOP:CONFIG:SECURITY:ACCOUNTING; move your cursor to Date Format
  309.   - Press F1 for an explanation of the format string
  310.  
  311.